MacWorld 1998 October/Macworld (1998-10).dmg/Shareware World/Utilities/DTP/Mark My Words/That Manual Thing

Text File | 1998-08-01 | 50.0 KB | 1,090 lines | [TEXT/ttxt]

That Manual Thing


Documenting: Mark My Words (version 1.0.2) © 1998 by Greg Swann


8/1/98


Greg Swann

[e-mail]
[e-mail]

USPS: 3608 West Cochise Drive
      Phoenix, AZ 85051



Table of Contents

1. Introductory chatter...

2. Commercial, legal and other pertinent notices...

3. Using Mark My Words: the big picture...

4. Where the bodies are buried...

5. Gloats and flourishes...

6. Mark My Words in real life...

7. About Greg Swann...

8. Conclusion...



1. Introductory chatter...

Mark My Words is a very elaborate MS-Word binary to XPress Tags text
filter. It eats Word 4.0, 5.0 or 5.1 files, interactively or by Drag
& Drop, and converts the binary to QuarkXPress tagged text.

Answering the question: why?

* The Word filter that ships with Quark would be half-witted with a
little more schooling. No beef, really, they're doing the 80% job
that one can expect of an import filter. But Mark My Words converts
100% of everything that can be produced in Quark, converts it
intelligently, and gives the user a very high degree of control over
the conversion, permitting, for example, the omission of unwanted
styling or the conversion of word processor-like styling to desktop
publishing-like styling.

* Word has the potential to be an excellent "Story Editor" for Quark
but for this: if you Save Text from XPress in Word format, you lose
a _lot_ of styling Quark can produce but Word cannot. But if you
save as XPress Tags, then edit in Word - _using_ Word styling such
Cmd-Shift-B - then run it past Mark My Words, you retain all the
original styling and all the new styling, plus you acquire the
ability to do corrections in a familiar way with familiar
keystrokes.

* Moreover, when drafting, you can key in XPress Tags constructs for
features that Word does not support. For example: you’re using
oodles of drop caps, and you’ve set up the styles the way you want
them in XPress. But you really want the drop caps to be scaled 80%
horizontally. Before, you had to either do the scaling in XPress
(inconvenient), or do all your styling with tags (mind-numbing). Now
you can do all your normal styling the Mac-way, and just throw a
<h80> and <h100>  around your drop caps. Mark My Words will do the
rest.

* Most significantly: converting the file to a text form with all
styling retained permits you to massage the text with Word, another
editor, or one of my text-banger utilities like ShawBerry or
Torquemada. If you import with the Word filter, you keep the styling
- even where it's bad - plus all the crap. With Mark My Words, you
can omit or convert the styling and you end up with a file that can
be cleaned up with very efficient tools. Moreover, the new file can
be run as is through XP8 to get a massive amount of quality
improvement for a negligible investment of labor.

Better filtration. Easier, faster editing. Infinitely better
quality. Win, win, win - surely a better way of working...

Mark My Words owes its origin to Shane Stanley. He wanted a way to
work in Word and yet gain access to XPress Tags. At first I wasn't
too sanguine about the idea, but I've learned to respect Shane's
hunches. I wasn't all that hungry for the ability to style the
Macintosh way, first because I don't create a lot of text for
publishing, and second because I'm used to styling the text I get
from clients directly in XPress Tags, using Torquemada. The bad part
about doing things that way was that I was losing the italic and
bold styling that the clients put into their files, which was a big
pain. So despite my doubts, I was way sold on the concept after we
finished WordLess Plus. I could keep what I wanted and throw away
the rest.

From the get, we knew we wanted to support Em Software's Xtags.
Xtags is a plug-compatible XPress Tags filter that offers a rich
superset of the XPress Tags commands. It is highly recommended to
Power Users of QuarkXPress. In MMW, we are supporting Xtags' ability
to create in-line text and picture boxes in a tag stream. The
advantage to this is, if you own Xtags, you can retain any pictures
or in-line tables that are in your Word files.

One of the original design goals was to permit iterative re-editing
(that is, taking a Word file, putting it through MMW, cleaning it
up, then doing additional edits back in Word, continuing to use
Word's styling commands, then putting it through MMW _again_, to
convert the added styling). WordLess Plus supported this after a
fashion, but Mark My Words does a much better job of it.

And: Shane wanted a way to insulate himself and others from bad
selections when editing. Suppose you have a Word file with explicit
tags in it, typed or inserted by Mark My Words, and you mis-select
some part of those tags and change the styling. For example, you
have:

<I>Lepton Local<I>

and you decide to make the title of that fine piece of software
Bold-Italic instead of just Italic. You mis-select, making this much
of the text bold:

>Lepton Local

If Mark My Words were not watching for exactly this kind of error,
you would get:

<I<B>>Lepton Local<BI>

which would choke the XPress Tags filter and elicit a nasty note
from Xtags.

Such deep thinkers are Shane and I that we've been pondering this
problem since MMW was a gleam in Shane's eye. Instead of the
erroneous tags above, MMW will produce:

<I><B>Lepton Local<BI>

No extra charge.

Finally, Shane and I went through about a bazillion rounds of User
Interface development. What we wanted was a UI that would permit
Power Users to take control over every little last thing but would
not present a dizzying array of choices to users less frenetic in
their pursuit of the arcane. I'm very proud of the results, and I
wish to thank Shane publicly, as so many times before, for the
gentle pushing he does in behalf of end-users (starting with
himself, of course (grin), but good products are made by designers
who are also hungry users).

I can't say enough good things about Shane, but I'll never stop
trying. If there's anything you hate in software by me, blame me.
But for anything you love, you can expect that at least part of the
credit owes to a light on in a house - and a mind - in Nar Nar Goon,
Victoria, Australia.

Mark My Words was tested by Shane, Mary Jo Kostya (requiescant in
pace), Kip Shaw, Mike Arst, Brad Walrod and Chris Ryland. Shane,
Mary Jo and Kip were the chief victims of a terrible anomaly found
late, since it affected only 68040 machines. This manual was looked
over by Shane, Mary Jo, Kip and Mike. None of them should be held
accountable for any part of it, of course, since I always do what I
want, despite excellent advice to the contrary.

On the subject: this file is written as plain text in DOS-like
fashion (i.e., every line ending is a carriage return). It is
produced in a FreeWare Programmer's editor called BBEdit by Rich
Siegel (which is recommended). I've had mail about this, so I'll
explain: I produce documents this way because doing so makes no
presumptions about what software and fonts you might own. _Most_
word processors can open, e.g., MS-Word files. But _all_ word
processors can open _this_ file.

The original FreeWare WordLess Plus is available and will always be
available for free. But: Mark My Words is commercial software: you
can't use it (for long) without paying me. The copy of Mark My Words
in this archive is a DemoWare version that will permit up to 32
launches and then forevermore refuse to do anything but be an
automated salesman. It is a _fully functional_ demo. Nothing is
crippled. A little bit of advertising is tacked on at the end of
each file, but everything works exactly as documented here. The only
inhibition is the one named: 32 launches, max. See "Commercial,
legal and other pertinent notices" below for information on how to
purchase unrestricted copies of Mark My Words.

TechnoBabble: Mark My Words is compatible with Systems 8, 7 and 6.
It is AppleEvent-aware, so, presumably, you could script to it. It's
32-bit clean, MultiFinder-aware, doubles on sax (turn up the
volume!), leaves no filmy residue on your fine china - all the usual
stuff. In short (there will be much more later), it's everything you
expect of up-to-the-microsecond Macintosh software.

And: this manual presumes a certain adeptitude with QuarkXPress and,
especially, XPress Tags (if you’ve never used them before, take a
look at Appendix C in the XPress manual). But to benefit from MMW,
you need only a basic understanding of how tagging works.

If you've been following my meteoric rise to obscurity, you know
that I'm an XPress Tags fanatic. If not, some explanation is due:
XPress Tags is a Text Only language built into QuarkXPress (since
version 3.0) that permits Quark to express and interpret almost
everything it can do. As such, it is richer than any other file
format Quark can import, and, hence, it allows users to do far more
styling and clean-up using automated tools such as my own Torquemada
and XP8. If this sounds like the "bad old days" to you, you're right
- it is. XPress Tags is a mark-up language, exactly like those used
in mainstream type systems and dedicated word processors. But: in
this one case, things were better when they were worse. If you get a
file that uses multiple spaces to pseudo-align columns, you can
spend all afternoon selecting those space and typing tabs, or you
can feed the file to XP8 and do the whole job plus a lot more in 10
seconds. If you want to get really radical with XPress Tags (not
necessary to the use of Mark My Words, but potentially very useful
in your daily work), a good place to begin is David Blatner's "The
QuarkXPress Book" (Peachpit Press).



2. Commercial, legal and other pertinent notices...

As mentioned above, this is a DemoWare version of Mark My Words,
fully functional but limited to 32 launches. The full unrestricted
commercial release can be obtained from Greg Swann at:

    [e-mail]

or

    [e-mail]

or

    Greg Swann
    3608 West Cochise Drive
    Phoenix, AZ 85051

Licenses are sold per machine, with a single license costing $50;
2-10 licenses are $45 each; and for 11 or more licenses you're
better off buying a site license. All of this is explained in the
registration software supplied with this archive.

Why is this version DemoWare? As with everything in my life, there
is philosophy here: I don't like crippled software. I don't think
much of ShareWare. And I almost never buy "a pig in a poke". In
deciding on a marketing scheme, I looked for something that would be
most appealing to _me_, were I in your shoes. This is what I've come
up with: a fully functional demo that lets you _find out_ if Mark My
Words is a useful tool in your working environment. If it is (and
obviously _I_ think it will be), then pay me. If it isn't, then
ditch it when it starts to offer to make coupons for you as a
full-time gig. A good deal all around, I think: no guilt for you, no
guilting for me; maybe useful software for you, maybe useful money
for me (grin).

Mark My Words, its source and executable code, and this poor excuse
for a manual are Copyright (C) 1998 by Greg Swann. All rights are
most emphatically reserved.

The unrestricted (non-DemoWare) version of Mark My Words is licensed
for use on one machine by the person who paid for it. If you didn't
pay for it, please do! I am one person, with a long-suffering
family, not Conglomerated MegaSoft (not to imply that there's any
virtue in ripping _them_ off!).

Mark My Words is delivered "as is", without any warranties,
expressed or implied. It is not warranted to be useful _to_ anyone,
_for_ anything, and in no wise am I to be held responsible for any
unfortunate consequences resulting from its use or misuse. And I
_hate_ having to say things like that. I do my best to write useful,
simple, elegant, bug-free solutions to difficult problems. If you
take it into your head that I represent your big chance to "strike
it rich", you will pay a lot in legal fees to discover that you have
miscalculated.

And: to those to whom the above disclaimers do not apply: forgive me
for having to make them. It's _you_ whom I'm working for, for pay or
for free. I appreciate your patronage and your support, and I wish
we all could just comb the others out of our hair...

(Hey, it's a real 'personal' software company! (grin))



3. Using Mark My Words: the big picture...

Mark My Words works on batches of files by Drag & Drop (under System
7 or above) or interactively from its main dialog (the Open...
button). Drag & Drop operation is relatively smart. In practice, the
program will only stay resident in memory if you are demonstrably
interacting with it. If you are doing no more than D&D batches, it
will quit at the end of each batch. Works like this:

D&D only: Quits

Double-click launch, then D&D: Quits

Double-click launch, then Open...: Stays resident

Double-click launch, hit any setting/menu, then D&D: Stays resident

We did it this way so that, if you are making temporary changes to
settings, you can still D&D, _but_ if you are just doing a D&D batch
(the likely normal procedure), MMW will get out of memory without
any effort on your part (nothing worse than having to Quit from a
bunch of small things to permit PhotoShop to launch).

Whatever the current state of your settings, you can get a Text Only
translation by holding down the Option key at the time that
execution begins. With the Open... button, you would hold down
Option as you hit the button. With a D&D batch, you would hold it
down as the batch begins. The override of the settings will affect
only that file or batch.

Mark My Words has a very large footprint in memory. Every major
decision came down in favor of speed, so we are consistently trading
memory for speed. The consequences are these: MMW is _substantially_
faster than WL+, even though it's doing a _lot_ more; and it eats
memory in big bites: the minimum memory required is approximately
384K + (sizeOfFile * 4). We ship with a 768K default, which is
adequate for most files. If a file is too large, you'll get an Alert
telling you how much to allocate.

The Preferences menu is familiar to anyone who's used anything
recent by me. "Restore defaults" restores all controls to their
"factory" default settings. "Restore saved prefs" resets all
controls to their state at the last time the preferences were saved.
And "Save preferences" saves the currently established settings;
these are the settings that you will see with subsequent launches
and after you hit "Restore saved prefs".

Where appropriate, CMD-C (Copy), CMD-X (Cut) and CMD-V (Paste) work,
even though there is no Edit menu.

The settings in the dialogs are fairly self-explanatory. Everything
is driven by the pop-ups in the Mark My Words Settings dialog box.
Operations can be controlled in a gross fashion with the pop-ups,
and, where appropriate, finer adjustments can be made in
sub-dialogs.

The Output format pop-up is interesting. Text Only is obvious.
XPress Tags is also familiar enough. But we are also, optionally,
parsing to Em Software's Xtags, a superset of XPress Tags. The
effect of other switches within the dialogs will depend on the state
of this pop-up. For example, if you have Retain Pictures checked,
embedded pictures will be saved to disk. If you are writing XPress
Tags, it will be up to you to get those pictures into Quark. But if
you are writing Xtags, we're plugging in Xtags coding to embed the
picture in the stream. (Necessarily, pictures are never other than
PICTs (i.e., RIP-crashers), because that's all that Word will store;
they are named intelligently ("YourFileName¶001", etc.) and live in
the same folder as the _original_ Word source file; with Xtags, the
size, scaling, and aspect ratios are maintained, but you are advised
to examine them to make sure they'll fit in your text link.)

In the same respect, the effects of tables and other in-line
elements depend on your choice of formats. With Xtags, we are doing
as much as possible to maintain the original coding. As above,
you'll need to make sure that things fit.

And: this may seem like overkill, given that most people don't use
these features of Word. They're included because: 1. some people
_do_, and 2. given that we now have a convenient way of doing this
stuff (by means of Xtags), it seems reasonable to suppose that we'll
find ways of taking better advantage of these features. For example,
Word's multi-cell tables, in conjunction with Xtags and Torquemada,
give us a way of producing side-by-side tables such as we haven't
seen in a while. (Take note that this feature is not supported by
Quark's Word filter.)

IMPORTANT: a Word file converted by Mark My Words to Xtags will
choke the XPress Tags filter and vice versa. In theory, these two
Xtensions are identical except for the Xtags extensions to the
XPress Tags language. In practice, there are subtle differences,
with the result that an MMW file written for one filter will not be
compatible with the other. Not such a big deal: you just have to
remember to use the filter you selected in MMW.

Output file type enables you to select the creator type of the TEXT
files MMW will produce. This is one of those features that's more
icing than cake, in my opinion. It means that you can double-click
on a file created by MMW and have your editor of choice launch,
instead of Mark My Words or the editor of _my_ choice (BBEdit). But:
given that we live in the age of Drag & Drop (don't we?),
double-click access to your editor is less vitally necessary than it
was under System 6.

The Style sheets pop-up lets you control how much of Word's style
definitions go out to the new file. Include definition writes out
the full definition at the start of the file with any
omitted/unsupported values omitted, which means they'll default to
Quark's values for the BasedOn style. We surmise that people can
have changed their default Normal in Quark, and, moreover, Normal
can't be redefined from tags. So when we Include definition, we are
showing Word's Normal as WordNormal=[S"Normal"]. That way, if there
are exceptions to Word's Normal, they'll be preserved in the
definition when the file gets to Quark. And if you've made changes
to Quark's Normal, those will be retained where they are not
overridden by exceptions in WordNormal. Note that all other styles
BasedOn No Style continue to be BasedOn No Style. Also: when we are
defining styles, we don't know yet if that style is actually used in
the text. So all defined styles are shown, and you may want to chop
some out prior to Getting Text.

Include name shows only the name of the style as it is called in the
text. This is the one to use if you want to retain Word's naming
convention, but expect to write all the style sheets in Quark (which
policy is recommended). In this instance, Word's Normal is shown as
Normal (i.e., BasedOn No Style), since there are no exceptions to
preserve.

All to normal ignores all style definitions and calls and simply
shows everything in the Normal style (which is either Quark's or
your own edited default).

Ignore completely ignores styles, period. Use this when you have
edited a previously Marked file and want to leave the styles alone.

The next three pop-ups are where the bullet hits the bone. And they
demonstrate rather nicely, I think, why Shane and I deserve to win
the award for User Interface design of the year (grin). What's going
on is this: by means of these pop-ups, you can effect either
wholesale or retail control over the conversion. "Retain all",
"Retain defaults" and "Omit all" are wholesale controls, while
"Custom settings..." permits you to tailor the conversion to your
needs and tastes.

This is slick and quick. It keeps the number of choices in the main
dialog to a manageable minimum and gives less-experienced users a
lot of control without requiring a lot of hirsute knowledge. But
there is more at work here: we are actually storing and accessing
the settings in two ways. If you go into a "Custom settings..."
sub-dialog and make some changes, then hit Okay, then change that
pop-up to "Retain all", then "Save preferences", what will happen is
this: both the settings in "Custom settings..." and the state of the
pop-up will be saved as preferences for future use. When you convert
a file, the state of the pop-up ("Retain all") will be honored, but
the settings you established within the "Custom settings..."
sub-dialog will persist, ready for easy access with the pop-up when
you need them. There's a similar kind of speed-up going on _inside_
the "Custom settings..." sub-dialogs by means of the "All on", "All
off" and "Prefs" buttons. Mark My Words is very fast at doing its
job, converting Word files to Tagged text. But it's also designed to
be very quick in its User Interface.

This is global information about the effect of the settings for the
"Paragraph styling", "Character styling" and "Ancillary coding"
pop-ups:

Retain all treats all check boxes as checked, treats all pop-ups as
though the second selection were picked, and enables all text edit
regions as their current settings. Retain defaults uses the factory
defaults, which is what you see if you Restore Defaults then examine
"Custom settings...". "Custom settings..." presents a dialog in
which you can change things to your liking. Omit all treats all
check boxes as unchecked, treats all pop-ups as though the first
selection were picked, and ignores the contents of the text edit
regions.

Within a "Custom settings..." sub-dialog, the "All on" button treats
all check boxes as checked, treats all pop-ups as though the second
selection were picked, and ignores the text edit regions. The "All
off" button treats all check boxes as unchecked, treats all pop-ups
as though the first selection were picked, and ignores the text edit
regions. The "Prefs" button resets all controls, including the text
edit regions, to their state when "Save preferences" was last
selected.

Repeating: the custom settings are honored _only_ if the "parent"
pop-up is set to "Custom settings..." If you make changes, hit OK,
then select Retain all, the custom settings will be preserved but
ignored during conversions, with the Retain all settings being used
instead.

The "Paragraph styling: Custom settings..." is the simplest of the
bunch: L&R indents, Leading, Alignment, Space before/after, Keep
w/next, First Line indents, and Tab settings are all obvious.

Important note about tabs: Word stores up to 50 tabs positions per
paragraph, while Quark stores only 20. One Word tab (the vertical
bar) can't be coded in Quark, so that saves us some slots. But: when
we get to the 21st tab we're done; no others are (or can be)
preserved. Moreover, the XPress Tags filter (as of version 1.5)
inadvertently throws away the 20th tab, so, in effect, with XPress
Tags (as of this writing) you have only 19 tabs; with Xtags, you
have the full 20.

For Keep together we are ignoring Word, which asks for <*ktA>, and
showing <*kt(2,2)> instead; the change reflects the difference
between word processing and desktop publishing.

Rules/Borders is a mutant: it's based on the Borders style in Word.
If a Border is established in a style's definition, we are showing
it as either a rule above and/or rule below, which means that the
rule(s) will show up in every paragraph in that style; nothing we
can do about that, since it comes with the style. However, when a
border is specified as an exception, we are showing the rule above
only above the first paragraph affected, and the rule below only
after the last paragraph, thus simulating as much as possible the
effect of the box in the original file. Since Word users can be way
stupid with boxes, and since, most often, their emphasis is entirely
redundant, my advice is to turn this off. At best, it flags
paragraphs thought worthy of emphasis by the WP operator.

There are a few things to discuss in "Character styling: Custom
settings..."  Style changes, Size changes, Font changes, and Color
changes are obvious.

The encapsulated font look-up table is used with Word 5.x files, so
you'll get true font names even though the fonts may not be loaded
or their numbers may be different. The font procedure for 4.0 files
is the same as that documented with WL+ - local system name if
fontID is loaded, fontID as text if not; that's what there is to go
by, alas.

The colors are the same brain-dead colors as in WL+ - nothing for
it, since that's all the colors there are.

Tracking changes: we're preserving this, but it's less than
perfectly useful. Word "tracks" with absolute values expressed in
quarter-points, range -7 to +56 quarter points. Too big for small
sizes, too small for big sizes, too stupid for words. We are
translating quarter points directly to Quark relative units. This is
not always awful, but it does always require follow-up scrutiny.

Super/subscript are translated Greg's way: <V> or <V->, IOW Superior
or Superior/Subscript. This seems to me to work better than Quark's
Superscript and Subscript styles, which I find to be too horsey, and
which frequently crash with the lines above and below. I have my
preferences set this way: 33% offset and 50% horizontal and vertical
scaling. Word uses pseudo-sub/superscripts in places (e.g.,
footnotes referenced by text instead of counters), and these are
treated as any other styled text (which is what they are).

In the pop-ups: Hidden text: Omit throws it away. Retain retains the
Hidden text as text, with no additional styling. Shade 0% retains it
shaded 0, the way WL+ did it. Strike-thru retains it in the </>
style. This option is there for this reason: Word's Table of
Contents and Indexing tools use Hidden text, of course. If you elect
to retain these features, you need some way of getting at the hidden
entries. </> is a very uncommon styling option (with good reason!),
so I selected it as a way of flagging this stuff. Why? I have hopes
that some enterprising Xtension developer will take advantage of
this free mark-up to write TOC and Indexing for Quark.

The Underlines conversion is pretty straightforward. Word has four
types of underlines, while Quark has only two. The deficit is hardly
to Quark's disadvantage - when was the last time you had a burning
need for a dotted underline? In any case, each of Word's underline
types can be either Ignored (i.e., passed as plain text), converted
to Italic, converted to the Underline style, or converted to the
Word Underline style. By default, Mark My Words converts all of
Word's undlerlines to Italic, since this is usually what is meant
(in DTP terms) by underscored text.

Ancillary coding... is where the rubber meets the road. You may be
asking yourself, "Why all this damned UI?" The reason is this: if
you know what you're doing, you can control every little last thing.
If you don't, we're trying to make it easy for you to stay out of
trouble. Ancillary coding... is the home of the stuff that it's
fairly dangerous to play with (grin).

TOC entries and Index entries are discussed above. These switches
control whether or not the Contents and Index subdocuments and the
Index/TOC markers (".i.", ".c.") will be emitted into the text
stream.

Page breaks allows or disallows page breaks (expressed as <\c>) in
the text, including the Page Break Before styling command.

Headers/Footers controls whether or not these subdocuments will be
emitted into the text stream.

Date/Time entries permits or forbids the insertion of text
translations of Word's date/time variables. If checked, the dates
and times will reflect the time of the conversion. This feature
takes account of your current Control Panels settings for dates and
times, so, presumably, they'll be dancing in the streets of old
Budapest tonight...

Footnotes allows or disallows inclusion of the footnotes
subdocument. Calls to footnotes in the text will remain, as is, in
the text.

In-line pictures is Xtags coolness #1. If there are pictures in the
file, if this box is checked, and if the output format is Xtags, the
pictures will be saved to disk as PhotoShop PICTs and the
appropriate Xtags coding will be plugged into the text. If the
format is XPress Tags, the pictures will be saved to disk, but the
user will be responsible for placing them. Equations made with
Word's equations editor are encapsulated QuickDraw PICTs, which
means they can be edited with a QuickDraw editor like MacDraw or
Canvas, and they will produce device-independent, object-oriented
images. Likewise, since PICTuresque can create PICTs with
encapsulated PostScript, this feature is at least slightly more than
interesting window dressing (grin).

In-line text boxes is Xtags coolness #2. This controls what happens
with Word's in-line tables and Word 5.1's (incredibly stupid) drop
caps. If checked, if Xtags, in-line text boxes will be parsed into
Xtags boxes with the appropriate coding. The boxes are sized
arbitrarily, so you'll either have to drag them out by hand or write
Torque sets to change them. If not Xtags, in-line text is emitted as
styled text. In the case of tables, cell and row boundaries are
flagged with tabs.

MMW comments inserts readable comments into the text, where
appropriate, if a feature is turned off. For instance, if Date/Time
entries is turned off, and a date is found, the text "{{Date}}" is
inserted at that spot. If you don't want comments inserted, uncheck
this box. This is the list of possible comments:

{{Table cell}}

{{In-line box}}

{{Picture: NameOfFile¶000}} <-XPress Tags

{{Picture}} <-Text Only

{{Date}}

{{Time}}

{{Page number}}

{{Footnote separator}}

{{Footnote continuation}}

{{Formula}} <-refers to formula glossary text not equations

Many of the Ancillary coding switches, including MMW comments, have
meaning even in a Text Only translation. For example, if Date/Time
entries is checked, then the dates and times will be converted. If
not, but MMW comments _is_, then the comment will be inserted. IOW,
Text Only means what it says: any controls that would create new
XPress tags are disabled, but the others remain in effect unless
explicitly switched off.

Below all this are two text edit regions, one for the default XPress
Tags version tag, which is also honored by Xtags, and one for the
default Xtags translation table. Note that either of these can be
"switched off" merely by deleting the text. Note also that each, if
present, is inserted anew into a file, each time it passes through
Mark My Words. So, if you mark a file, then take it back to Word for
further editing, then mark it again, the old version and Xtags &tt2
tags will be ripped out and replaced by whatever is the currently
established default. FWIW, while the version tag for 3.2 will be
1.6, MMW is writing XPress Tags 1.5/Xtags 1.0 compliant tags. Filter
1.6 offers very little new coding, and most of it is not relevant to
Word. The only 1.6 construct in MMW is
[S"BasedOnStyle","NextStyle"], used only in XPress Tags
translations. Filter 1.5 ignores this construct, but filter 1.6 will
accept it _if_ your version tag is set for 1.60.



4. Where the bodies are buried...

* I wish I had greater control over the in-line text boxes. I was
compelled to use arbitrary box sizes because of the idiotic way Word
stores the sizing information.

* The formula glossary text is far from ideal, largely because Word
is interpreting formulae on the fly (and has a lot of positioning
controls Quark doesn't have).

* The Rules/borders solution is the best answer we could come up
with to an ugly problem.

* As regards running the same text through MMW more than once, the
feature is robust but not fool-proof. If you're just doing text
editing, set Style sheets to Ignore. Any character or paragraph
property exceptions you introduce will be honored, but the style
sheets won't be parsed. If, OTOH, you want to define new styles, you
can. Just Include definition. Take note, however, that WordNormal
and any other default styles you have defined (i.e., present in all
new documents) will be parsed again. You'll need to go through the
styles and chop out the replacements. This is important because
Quark does not redefine styles; the first definition found for a
particular name is the one used, and later definitions under that
name are ignored (this, essentially, is why you can't redefine
Normal).



5. Gloats and flourishes...

* Word, like Quark, is massively redundant. We are watching what
we're doing as we work and we issue styling only where an actual
change has occurred. No harm comes of writing extremely redundant
Tags, as does the QXPTags export filter, but doing it this way makes
things a lot easier on us wetware types.

* If you've used Quark's Word filter, you know that Quark and Word
do not agree about what happens to character styling at style
boundaries. Word retains the exceptions, while Quark wipes the slate
and baselines everything to the style. Taking account of this
conflict, Mark My Words reissues any pending styling exceptions when
a style boundary is crossed. IOW, MMW tags behave like the Word
file, and not like the Word-filter imported text.

* We are doing everything we can to shoehorn Word's 50 tabs into
Quark's 20 slots. The sequence for an exception is delete, compact,
add, sort, compact, with the whole point being never to waste a
slot. Word's (wonderful!) vertical line tab is omitted, of course.
But, at bottom, when we get to the 21st tab, we're done - the rest
are tossed.

* It's _real_ fast... (grin)



6. Mark My Words in real life...

The mis-selection business works like this: before we apply any
styling, we are looking at the raw text. Where we spot an open angle
bracket, we are looking ahead to see if it is legally terminated. If
it isn't we are insulating it as "<\<>" (the XPress tags way of
showing an open bracket as text). We are doing the same thing for
illegal closing angle brackets ("<\>>"). That way, we can be assured
that every angle bracket found in the text is part of a legal XPress
tag. Then, when we get around to looking for improperly nested tags
(e.g., <I<B>>, as shown above), we can easily switch things around
without worrying that we're hosing good text.

Important: the MMW tag insulation is not as good as XP8's. We're not
striving to identify improperly formatted tags, but, rather, to
insulate the genuine impostors. Likewise: unlike XP8, we are not
doing anything about "@" and "\" when they are used as text.
Properly, these should be shown as <\@> and <\\>. To be safe(r), you
should still run the MMW file through XP8. Then use Xtags, of
course, since, while XPress tags filter 1.6 will be a lot better
about this than 1.5, Xtags' error-reporting still blows it out of
the water.

Moreover, you are ever and always on your own when it comes to tags
that are legal but illogical. If you have this as text:

<<B>>

Mark My Words will know enough to make it look like legal XPress
tags (<\<><B><\>>), but that <B> in the middle is legal and will
pass the test of quality in MMW, in XP8, in XPress tags and in
Xtags. Everything after it will be bold until it is turned off. In
other words: while software can protect you from obvious,
identifiable errors, it can never be a substitute for an active
human intelligence.

On the same planet: if you have a file (like this one) that is
filled with clearly legal XPress Tags that are _not_ intended to be
interpreted as XPress Tags, you need to insulate them on your own,
since no software is going to reject perfectly legal tags. You can
search for, e.g., "<" and replace with "<\<>", but that seems to me
to beg for errors. What I do is this: I search for "<" and replace
with "«" (option-backslash; closing form is shift-option-backslash).
That keeps approximately the same look, and it's easy enough to
switch back when I get to XPress. The point is this: if it's not to
be interpreted as a tag, it can't _look_ like a legal tag.

Next up: Xtags looks for pictures only by absolute path (like
Quark). I omitted paths in the picture specifications so you _could_
move the pics if you wanted; otherwise Xtags would insist they
remain where birthed, and Quark would still only let you move them
into the same folder as the Quark file without relinking. Ergo, move
a standing Quark file or Save a new file into the folder where the
pictures reside prior to doing Get Text With Xtags.

IMPORTANT (and easy to forget): If the Quark file and the pictures
are not resident in the same folder, Xtags won't find them.

On the point: those Xtags text and picture boxes are cool, but each
one is a Quark object. That means that each one takes time to
create, and more time, ever and always, for Quark to manage. A word
to the wise is sufficient: if you create a file with thousands of
objects, expect to do a lot of waiting...

And: if you don't have an Xtags translate table, delete the text for
it in in Ancillary coding and Save Prefs. If no text, no tag. I
myself have a table named "YourTableName" (grin - but I'm not
kidding).

Mark My Words will not process Fast Saved files. Sorry. We had
wanted to do it with this version, but I deliberately walked away
from it because Word files are entirely too attenuated as it is. If
you select or D&D a Fast Saved file, MMW will display an Alert then
get on to the next task.

There are a certain few other occasions where Mark My Words will
fail (ever gracefully) to process a file. For example, files
produced by versions of Word earlier than 4.0 are politely refused.
And: files that are excessively complicated are deflected. In the
former event, open the file from Word and Save As in a version less
historic. In the latter case, chop the file up into smaller chunks
and feed them to MMW in a batch. For reference: a file will be
refused on the grounds of complexity if it entails more than 8192
character styling or 8192 paragraph styling changes. This limit is
eight times that imposed by WordLess Plus, and you may be delighted
to hear that we haven't been able to hit it in extremely complicated
testing files weighing in at over a quarter-megabyte. In other
words, complexity is mostly a non-issue.

Real life: Word plus Mark My Words make a better front end to Quark
than anything we now have available. In the long run, I intend to
make something better, but this will do for now. The advantages are
these: You can draft as Styled Text, using the familiar Keyboard
Equivalents, as opposed to typing verbose and obscure XPress Tags.
Moreover, the people who type for you can give you what you need
without your having to teach them very much. The resultant files can
be run through Mark My Words, Torquemada, and XP8. And then, if you
want, you can open them _again_ from Word, do the edits as Styled
Text, run through Mark My Words again, etc. You can work with tags
without having to type (and _check!_) each and every one.

If you are lucky enough to have people typing for you who do what
you say, you can introduce their files to Torquemada and have a
great deal of the up-front labor of your jobs done for free. For
example, if some words of a paragraph need to swap out to a PMS
color, you can have the keyboarder style that text as "Blue", then
search in Torquemada, replacing "Blue" with the true name of the
color. Or you can use XP8's mnemonics or a code of your own devising
to flag special situations and dingbat characters, then use XP8 or
Torquemada to plug in the true XPress Tags coding.

Unless you turn this feature off, every Mark My Words file begins
with the XPress Tags version tag ("<v1.60><e0>"). This is included
because Mark My Words makes use of the Baseline Shift tag ("<bXX>"),
and Quark varies its interpretation of that tag based on the
presence or absence of the version tag. Without it, the file is
interpreted as being a Quark 3.0 file, and the effect of the
Baseline Shift is inverted (viz., positive values shift down instead
of up, replicating a bug in the XPress Tags filter that shipped with
Quark 3.0). If you are still running XPress 3.0 (why?), you will
need to do two things: lose the version tag and invert the signs of
all baseline shifts. These Torquemada strings should serve to do
both:

<v^?^p        {nothing}        Omit the version tag

-b^#        |b^#            Mark the negative values

b^#            -b^#            Invert the positive values

|-            {nothing}        Remove the marks

In the same neighborhood: the second half of the version tag
("<e0>") is a language identifier. If you are working with a
non-English version of Quark, you may need to change this to the
code shown when you Save Text as XPress Tags from within Quark.

Likewise: we are converting the QuickDraw colors in Word using their
English names (e.g., "Black", "Blue"). I don't know if non-English
versions of Quark tags use non-English names for the QuickDraw
colors, but, if they do, and if you're competent with ResEdit, you
can "internationalize" these colors fairly simply by editing STR#
resource number 133. Change only the literal name of the color,
leaving the quote marks alone. Sequence is significant, so translate
the color names "in place" (e.g., "Schwarz" for "Black", not
"Blue"). If you work in multiple languages, you can spawn versions
of MMW, one for each language you use. Presumably, nothing else
about XPress tags is language-sensitive, but if that turns out not
to be the case, do please let me know. We strive to make our
software as international as possible, and we fail through ignorance
rather than lack of trying.

And one more: as a default, we are showing Word's numbered footnotes
in Quark's Superior style. Alas, there is no clear-cut way of
dealing with footnotes flagged manually with user-supplied text.
These are being shown the way that Word is storing them. For
example, they might come across as "<z9.0b3.0>". If you have
footnotes of both types in the same file, you'll need to search to
bring them into concordance.

Useful: Word 5.x does an excellent job of filtering a number of
alien file formats. It sees all its own historical versions, of
course, plus all of the many version of DOS Word. But it also does a
great job with, e.g., WordPerfect for Mac and DOS. The best thing to
do with an alien file is to get it into Word in some way, preferably
from Word 5.x, from MacLink or Software Bridge otherwise. Then Save
As a Word 5.x file and run the resultant file through Mark My Words.
This is the most efficient means you have of retaining the maximum
amount of supplied paragraph and character formatting.

Eminently nerd-like hack: every piece of software by me that has a
Preferences menu (Shane the Plane, Clip 'n' Save, ShawBerry, and
Mark My Words) stores its preferences in the resource fork of the
software itself. The Default prefs are stored in 'PREF' resource
128, and the Saved prefs are stored in PREF 129. When you Save
preferences, PREF 129 is re-written with your new settings. If you
are comfortable with ResEdit, you can use it to give yourself two
sets of stored preferences. Do this (on a _copy_ of Mark My Words,
of course):

1. Establish your second-favorite settings and Save preferences.
Quit.

2. Open the copy of Mark My Words from ResEdit, and navigate your
way to PREF 129. Select all and Copy.

3. Open PREF 128, Select All and Paste. Save and Close the file. The
two resources are now identical, with both containing your
second-favorite settings.

4. Launch Mark My Words again and establish your (first-)favorite
settings and Save preferences. Now when you do Restore defaults,
you'll get your second-favorite settings, and when you do Restore
saved prefs, you'll get your (first-)favorite settings, which will
also be loaded automatically with every subsequent launch.



7. About Greg Swann...

Okay, here's the deal: I'm not just a developer, I'm a user of
software as well. I make about half of my money doing Desktop
Publishing. In consequence, I have a pretty clear idea of how to
focus utilities designed to plug gaps in the functionality of major
applications. I am quite sure there are a _lot_ of developers
brighter than I am. But the evidence of experience suggests that few
of them have my advantage of living on both sides of the line, so to
speak.

What does this mean?

First, it means that I have written a _lot_ of mission-critical
utilities in support of the software categories of interest to me:
file management, font management, automated text processing,
PostScript-processing, and automated DTP-software preparation. All
but four of these utilities are FreeWare (the exceptions being Mark
My Words and the three packages discussed below) and are available
from Info-Mac and other electronic information services (including
any service offering access to the Arizona Macintosh User's Group
BBS-In-A-Box CD-ROM).

Second, it means that if you are likewise interested in these
software categories, it behooves you to support my work. Fanmail is
always nice, of course, but remuneration is the sincerest form of
flattery (grin). Seriously: this is a business, even if a
microscopically small one. It has been worthwhile so far because the
other things commanding my attention have not been as lucrative. But
that is changing (of course, and obviously, _because_ of all the
software). I can make a _lot_ of money writing custom software for
contracted clients. And I can streamline my own production work
without having to monkey-proof and document my tools. So: if I am to
keep doing this, I have to make it pay. If you _want_ me to keep
doing it, you have to pay me. It's that simple.

In many ways, retail software is simpler. You pay or you don't play,
and no one has any illusions. The difference is, the developer needs
a _much_ larger capital commitment, and he needs to surround himself
with babbling morons in suits who might - just possibly - be good
for something other than chuckling about football. Electronically
distributed software gets around that trap, but introduces the
problem exposed here: the ambiguity of the sales transaction results
in a lot of prostrate begging by developers. I don't beg, but I
don't work for free except on my own terms for my own good reasons.

There are three possible "futures" for authors of electronically
distributed software. 1. The rewards do not justify the effort, so
the author goes and plays tennis or something. 2. The author
produces software as an after-work hobby and continues to do so more
or less irrespective of user-response (some of the best and worst
FreeWare comes out of this category). 3. The author's growing
reputation results in him getting more contracted custom programming
work, worth more money, to the point that he no longer has time to
produce electronically distributed software.

It is the last that is happening to me, and this is why you need to
support my work, if you want it to continue. I'll do all right
whether I'm working on problems that confront you or on the problems
of some corporation. But: if you are using software by me that has a
commercial version (and all of them are discussed here), and if you
want me to _continue_ thinking about your problems, rather than the
problems of Consolidated MediCalc - you know what to do...

These are my commercial programs:

XP8 - a very intelligent file filter that cleans up and makes the
filthiest text QuarkXPress-ready. Among many other features, it
offers DOS-file reformatting, financial-text clean-up, garbage
disposal, typographic quality enhancement, and the best quote
conversion we know of. The ShareWare version of XP8 (v1.0.0) can be
found in CompuServe's Desktop Publishing Forum (GO DTPFORUM),
Library 5, under the name XP8.SEA or in the Info-Mac archives as
GST-XP8Demo.sit. The current commercial version is v1.0.7 and offers
a great many enhancements over the ShareWare version.

Torquemada The Inquisitor - batch global search and replace software
with wildcards, pattern matching, string substitution, et very
cetera. With Drag & Drop under System 7 and above, you can run up to
640 searches on up to 128 files in one batch. Features the most
intelligent case-conversion we know of. The most-recent FreeWare
version (1.1.0) can be found under the name TORQUE.SEA in Library 5
or in the Info-Mac archives as GST-TorqueDemo.sit. The current
commercial version is 1.3.0, offering a great many enhancements,
including new "wildthings" and a _lot_ of new User Interface power.
The commercial version ships with Torquemada's Ghost, a scriptable,
backgroundable Torquemada. A DemoWare version of Torquemada's Ghost
is available as TGHOST.SEA in Library 5 or in the Info-Mac archives
as GST-TGhostDemo.sit.

Shane the Plane 2.0.2 - file and font attribute editing utility.
Interactively or in Drag & Drop batches, permits you to change the
Creator/Type of files, their created/modified dates and times, a
host of significant Finder flags, plus a lot more. Makes files
invisible/visible, makes fonts behave like files by removing their
BNDL resources, batch "pastes" custom icons, intelligently renames
and/or "slugs" files, et very cetera. A demonstration version (fully
functional but limited to 32 launches) can be found in Library 12
under the name SPDEMO.SEA or in the Info-Mac archives as
GSU-STPDemo.sit.

Mark My Words - a very elaborate MS-Word binary to QuarkXPress Tags
text filter. It eats Word 4.0, 5.0 or 5.1 files, interactively or by
Drag & Drop, and converts the binary to QuarkXPress tagged text. You
can elect to include or omit any feature of Word's styling, and many
features can be converted from their WP-like form to their DTP-like
form (e.g., underscoring to italic). With Em Software's Xtags
Xtension, picture and text boxes (including Word's tables) can be
retained. A demonstration version (fully functional but limited to
32 launches) can be found in Library 12 under the name MMWDEM.SEA or
in the Info-Mac archives as GST-MMWDemo.sit.

(While I've vectored all the files toward CIS and the internet, my
primary haunt, they are also available on other services, and on any
BBS which has the most recent version of AMUG's BBS-In-A-Box CD-ROM
on line.)

All of these programs are sold on the same terms: (US)$50 each, per
license. Two to 10 licenses are $45 each. For 11 or more licenses
you're better off buying a site license. All of this is explained in
the registration software supplied with this archive.

These programs are included on the distribution disk for the
unrestricted version of Mark My Words:

* Mark My Words v1.0.0 - discussed here at some length (!)

* XP8 v1.0.0 - ShareWare version of the commercial software

* Torquemada the Inquisitor v1.1.0 - FreeWare version of the
commercial software

* A Sort of a Kind - very fast, very robust text file sorting
utility

* FontFischer - font specimen book creation utility

* PixPex - Drag & Drop Xtags picture box creation utility

* ShawBerry - text file merging utility

Plus some other stuff...



8. Conclusion...

Jeez, haven't you had _enough_...? (grin)

Seriously: that's it. If you have any questions or problems, the
easiest way to get hold of me is by email at:

    [e-mail]

If you can't do that, you can snail mail me at:

    Greg Swann
    3608 West Cochise Drive
    Phoenix, AZ 85051



Very Best,



Greg Swann

8/1/98